{
 "cells": [
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# ```query()``` function"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "The query function issues a query to a specific API endpoint and return the result in a Pandas DataFrame.\n",
    "It should be executed after you get connected to the website using the connect function.\n",
    "\n",
    "In this section, we show what parameters are available and examples of how to call the query function.\n",
    "\n",
    "\n",
    "The query function adopts async IO.\n",
    "\n",
    "####  To call from a Jupyter notebook, you can use\n",
    "\n",
    "```\n",
    "df = await conn.query(...)\n",
    "```\n",
    "\n",
    "#### Otherwise, use\n",
    "\n",
    "```\n",
    "import asyncio\n",
    "df = asyncio.run(conn.query(...))\n",
    "```"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Parameters\n",
    "\n",
    "* ```table``` is the path to the configuration file folder. There are two ways to load it. Details can be found in the previous configuraton file section.\n",
    "\n",
    "* ```_q (optional)``` is the search keyword.\n",
    "\n",
    "* ```_auth (optional)``` pass the authorization credentials. Usually the authentication parameters should be defined when instantiating the Connector. In case some tables have different authentication options, a different authentication parameter can be defined here. This parameter will override the one from Connector if passed.\n",
    "\n",
    "* ```_count``` is the number of results to be returned. Our auto-pagination scheme makes it possible to get results from multiple pages using one function call. See details in later sections.\n",
    "\n",
    "* Other parameters are defined in the configuration file. You can view them using ```info()```."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Examples\n",
    "\n",
    "Below shows some possible ways to call the query function.\n",
    "\n",
    "* **dblp** \n",
    "\n",
    "```\n",
    "df = await conn.query(\"publication\", q=\"CVPR 2020\", _count=2000)\n",
    "```\n",
    "\n",
    "Through this query, we fetch the top 2000 search results for keyword \"CVPR 2020\" via dblp publication API.\n",
    "\n",
    " \n",
    "* **YouTube**\n",
    "\n",
    "```\n",
    "df = await dc.query(\"videos\", _q=\"Data Science\", part=\"snippet\", type=\"videos\", _count=40)\n",
    "```\n",
    "This line of code queries the YouTube video search API for 40 results with keywords \"Data Science\".\n",
    "```part=\"snippet\", type=\"videos\"``` are additional filtering conditions defined in the YouTube API.\n",
    "\n",
    "\n",
    "* **Twitter**\n",
    "\n",
    "```\n",
    "df = await dc.query(\"tweets\", _q=\"COVID-19\", _count=50)\n",
    "```\n",
    "This query searches 50 results for tweets related to COVID-19 from Twitter search API."
   ]
  }
 ],
 "metadata": {
  "kernelspec": {
   "display_name": "Python 3",
   "language": "python",
   "name": "python3"
  },
  "language_info": {
   "codemirror_mode": {
    "name": "ipython",
    "version": 3
   },
   "file_extension": ".py",
   "mimetype": "text/x-python",
   "name": "python",
   "nbconvert_exporter": "python",
   "pygments_lexer": "ipython3",
   "version": "3.7.7"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 4
}
